home *** CD-ROM | disk | FTP | other *** search
/ DOpus Plus / DOpus Plus.iso / SDK / docs / images.doc < prev    next >
Encoding:
Text File  |  1998-10-26  |  10.7 KB  |  332 lines
  1. dopus5.library/CloseImage                           dopus5.library/CloseImage
  2.  
  3.     NAME
  4.         CloseImage - close an image
  5.  
  6.     SYNOPSIS
  7.         CloseImage(image)
  8.                      A0
  9.  
  10.         void CloseImage(APTR);
  11.  
  12.     FUNCTION
  13.         Closes an image that was opened with OpenImage(). The usage count
  14.         of the image is decremented. When the count reaches 0 the image is
  15.         flushed from memory.
  16.  
  17.     INPUTS
  18.         image - image to close
  19.  
  20.     SEE ALSO
  21.         OpenImage()
  22.  
  23. dopus5.library/CopyImage                             dopus5.library/CopyImage
  24.  
  25.     NAME
  26.         CopyImage - copy an opened image
  27.  
  28.     SYNOPSIS
  29.         CopyImage(image)
  30.                     A0
  31.  
  32.         APTR CopyImage(APTR);
  33.  
  34.     FUNCTION
  35.         Returns another pointer to the supplied image.
  36.  
  37.     INPUTS
  38.         image - image to copy
  39.  
  40.     RESULT
  41.         Returns a new pointer to the image.
  42.  
  43.     SEE ALSO
  44.         OpenImage()
  45.  
  46. dopus5.library/FreeImageRemap                   dopus5.library/FreeImageRemap
  47.  
  48.     NAME
  49.         FreeImageRemap - free pens used to remap images
  50.  
  51.     SYNOPSIS
  52.         FreeImageRemap(remap)
  53.                          A0
  54.  
  55.         void FreeImageRemap(ImageRemap *);
  56.  
  57.     FUNCTION
  58.         Frees all the pens allocated with the supplied ImageRemap structure.
  59.         You should call this function after you have called FreeRemapImage()
  60.         or CloseImage() on the individual images.
  61.  
  62.     INPUTS
  63.         remap - ImageRemap structure to free
  64.  
  65.     SEE ALSO
  66.         RemapImage()
  67.  
  68. dopus5.library/FreeRemapImage                   dopus5.library/FreeRemapImage
  69.  
  70.     NAME
  71.         FreeRemapImage - free a remapped image
  72.  
  73.     SYNOPSIS
  74.         FreeRemapImage(image, remap)
  75.                         A0     A1
  76.  
  77.         void FreeRemapImage(APTR, ImageRemap *);
  78.  
  79.     FUNCTION
  80.         This function frees the remapped bitplanes allocated for an image
  81.         via the RemapImage() call.
  82.  
  83.     INPUTS
  84.         image - image to free remap bitplanes for
  85.         remap - ImageRemap structure
  86.  
  87.     RESULT
  88.         The remapped bitplanes are freed. This routine does not free any pens
  89.         that were allocated - these are released when you call FreeImageRemap().
  90.         Note that the image itself is not freed, only the remapped version of
  91.         it.
  92.  
  93.     SEE ALSO
  94.         RemapImage(), FreeImageRemap()
  95.  
  96. dopus5.library/GetImageAttrs                     dopus5.library/GetImageAttrs
  97.  
  98.     NAME
  99.         GetImageAttrs - get information about an image
  100.  
  101.     SYNOPSIS
  102.         GetImageAttrs(image, tags)
  103.                        A0     A1
  104.  
  105.         void GetImageAttrs(APTR, struct TagItem *);
  106.  
  107.     FUNCTION
  108.         This routine allows you to retrieve information about an image opened
  109.         with OpenImage().
  110.  
  111.     INPUTS
  112.         image - image to investigate
  113.         tags - control tags. The following tags are valid :
  114.  
  115.                IM_Width             - width of image
  116.                IM_Height            - height of image
  117.                IM_Depth             - number of bitplanes
  118.                IM_State             - 1 if the image has two frames, 0 if not
  119.  
  120.     RESULT
  121.         The requested information is stored in the ti_Data field of each of
  122.         the Tags passed in.
  123.  
  124.     SEE ALSO
  125.         OpenImage()
  126.  
  127. dopus5.library/GetImagePalette                 dopus5.library/GetImagePalette
  128.  
  129.     NAME
  130.         GetImagePalette - get pointer to image palette
  131.  
  132.     SYNOPSIS
  133.         GetImagePalette(image)
  134.                          A0
  135.  
  136.         ULONG *GetImagePalette(APTR);
  137.  
  138.     FUNCTION
  139.         This allows you to retrieve a pointer to the palette of the image.
  140.  
  141.     INPUTS
  142.         image - image you want the palette for
  143.  
  144.     RESULT
  145.         If the image has associated palette information (eg a brush), a
  146.         pointer to a longword palette table is returned. This palette table
  147.         is in LoadRGB32() format. If the image has no associated palette,
  148.         this routine returns NULL.
  149.  
  150.     SEE ALSO
  151.         OpenImage(), graphics.library/LoadRGB32()
  152.  
  153. dopus5.library/OpenImage                             dopus5.library/OpenImage
  154.  
  155.     NAME
  156.         OpenImage - read an image off disk
  157.  
  158.     SYNOPSIS
  159.         OpenImage(name, info)
  160.                    A0    A1
  161.  
  162.         APTR OpenImage(char *, OpenImageInfo *);
  163.  
  164.     FUNCTION
  165.         The primary purpose of this function is to read an image from a file
  166.         on disk. This routine supports ILBM brushes and pictures, animbrushes
  167.         and Amiga icons.
  168.  
  169.         This routine is also used to create an image handle to bitmap data
  170.         that you supply. This image handle can then be used with the image
  171.         remapping functions.
  172.  
  173.         This function caches images based on their full pathname. If two
  174.         copies of the same file are loaded, the first copy will be used to
  175.         save memory.
  176.  
  177.     INPUTS
  178.         name - name of image to load, or NULL if you are supplying a bitmap
  179.         info - if 'name' is NULL, this must point to an initialised
  180.                OpenImageInfo structure:
  181.  
  182.                     oi_ImageData - must point to the image data. This data
  183.                     does not need to be in chip memory.
  184.  
  185.                     oi_Palette - must point to a palette for the image, in
  186.                     LoadRGB32() format.
  187.  
  188.                     oi_Width - width of the image
  189.  
  190.                     oi_Height - height of the image
  191.  
  192.                     oi_Depth - number of image bitplanes
  193.  
  194.     RESULT
  195.         Returns an image handle if it succeeds. This handle is used in
  196.         subsequent calls to the image routines. This routine returns NULL if
  197.         it fails.
  198.  
  199.     SEE ALSO
  200.         CloseImage(), graphics.library/LoadRGB32()
  201.  
  202. dopus5.library/RemapImage                           dopus5.library/RemapImage
  203.  
  204.     NAME
  205.         RemapImage - remap an image
  206.  
  207.     SYNOPSIS
  208.         RemapImage(image, screen, remap)
  209.                     A0      A1      A2
  210.  
  211.         BOOL RemapImage(APTR, struct Screen *, ImageRemap *);
  212.  
  213.     FUNCTION
  214.         This function remaps an image to the colours of the specified screen.
  215.         It will allocate pens from the screen if necessary (and possible).
  216.  
  217.     INPUTS
  218.         image - image to remap (from OpenImage())
  219.         remap - ImageRemap structure. This structure must be initialised for
  220.                 the first call to RemapImage(). All fields must be set to
  221.                 NULL.
  222.  
  223.                 For the first and subsequent calls to this function, the
  224.                 ir_Flags field can be set with the following values :
  225.  
  226.                     IRF_REMAP_COL0      - remap colour 0 in the image
  227.                     IRF_PRECISION_EXACT - use best precision when pen matching
  228.                     IRF_PRECISION_ICON  - lower precision
  229.                     IRF_PRECISION_GUI   - lowest precision
  230.  
  231.                 You can use the one ImageRemap structure to remap multiple
  232.                 images, but only for the one screen. The ir_Flags field can be
  233.                 changed for every call to this function, but none of the
  234.                 other fields may be changed.
  235.                 
  236.     RESULT
  237.         This image returns TRUE if it was able to remap the image. Once the
  238.         image has been remapped, any call to RenderImage() to display it will
  239.         show the remapped version. Call FreeRemapImage() to free the remap
  240.         and return to the original image.
  241.  
  242.     SEE ALSO
  243.         OpenImage(), RenderImage(), FreeRemapImage(), FreeImageRemap()
  244.  
  245. dopus5.library/RenderImage                         dopus5.library/RenderImage
  246.  
  247.     NAME
  248.         RenderImage - display an image
  249.  
  250.     SYNOPSIS
  251.         RenderImage(rp, image, left, top, tags)
  252.                     A0    A1    D0   D1    A2
  253.  
  254.         short RenderImage(struct RastPort *, APTR, USHORT, USHORT,
  255.                           struct TagItem *);
  256.  
  257.     FUNCTION
  258.         This routine is used to render an image to a RastPort.
  259.  
  260.     INPUTS
  261.         rp - RastPort to render to
  262.         image - image to render
  263.         left - x position to render to
  264.         top - y position to render to
  265.         tags - control tags. The following tags are available :
  266.  
  267.             IM_State - 0 or 1 (default 0)
  268.  
  269.                 This tag controls which frame of the image is shown.
  270.                 Defaults to frame 0, but for two-frame images (eg icons or
  271.                 animbrushes) you can set this to 1.
  272.  
  273.             IM_Rectangle - struct Rectangle * (default not supplied)
  274.  
  275.                 This specifies a rectangle to display the image within. If
  276.                 you supply this tag, the image will be centered within this
  277.                 area. Use of this tag overrides the 'left' and 'top'
  278.                 parameters. 
  279.  
  280.             IM_ClipBoundary - integer (default 2)
  281.  
  282.                 This is used with the IM_Rectangle tag. If IM_Rectangle is
  283.                 specified, the image is clipped to the boundaries of the
  284.                 rectangle. The default operation is to leave a two pixel
  285.                 margin around the image (to allow room for a border). Using
  286.                 the IM_ClipBoundary tag you can adjust this margin (set to 0
  287.                 if you want no margin).
  288.  
  289.             IM_Mask - TRUE or FALSE (default FALSE)
  290.  
  291.                 If you set this tag to TRUE, the image will be masked when
  292.                 it is rendered. This has the effect of making colour 0
  293.                 transparent, and the existing background will show through
  294.                 the image.
  295.  
  296.             IM_Erase - integer (default not supplied)
  297.  
  298.                 This tag allows you to specify a pen value that is used to
  299.                 erase the background before the image is rendered. By
  300.                 default the background is not cleared.
  301.  
  302.             IM_NoDrawInvalid (default not supplied)
  303.  
  304.                 If you specify this tag, and also specify 1 for IM_State,
  305.                 then the call to RenderImage() will fail if the image has
  306.                 no secondary image. If this tag is not specified and you
  307.                 try to draw the second frame of an image that doesn't have
  308.                 one, it falls back to drawing the first frame.
  309.  
  310.             IM_NoIconRemap - TRUE or FALSE (default FALSE)
  311.  
  312.                 By default, an icon that is drawn with RenderImage() is
  313.                 "remapped". This is not a true colour remapping, but the
  314.                 third bitplane of an eight colour icon is shifted to the
  315.                 top bitplane of the display. This makes most normal eight
  316.                 colour icons work properly on screens of more than eight
  317.                 colours. However, it can cause problems with NewIcons
  318.                 icons. Specify TRUE with this tag to disable this remapping.
  319.  
  320.     RESULT
  321.         The image is rendered. If you specified IM_NoDrawInvalid and you
  322.         tried to draw an image that didn't exist, this routine returns FALSE.
  323.         Otherwise it returns TRUE.
  324.  
  325.     NOTES
  326.         If the image has been remapped with RemapImage(), the remapped image
  327.         will be automatically drawn by this routine.
  328.  
  329.     SEE ALSO
  330.         OpenImage(), RemapImage()
  331.  
  332.